<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>sem_open</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_008_306">&nbsp;</a>NAME</h4><blockquote>
sem_open - initialise and open a named semaphore
(<b>REALTIME</b>)
</blockquote><h4><a name = "tag_000_008_307">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="semaphore.h.html">semaphore.h</a>&gt;

sem_t *sem_open(const char *<i>name</i>, int <i>oflag</i>, ...);
</code>
</pre>
</blockquote><h4><a name = "tag_000_008_308">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>sem_open()</i>
function establishes a connection between a named semaphore and a process.
Following a call to
<i>sem_open()</i>
with semaphore name
<i>name</i>,
the process may reference the semaphore associated with
<i>name</i>
using the address returned from the call.
This semaphore may be used in subsequent calls to
<i><a href="sem_wait.html">sem_wait()</a></i>,
<i><a href="sem_trywait.html">sem_trywait()</a></i>,
<i><a href="sem_post.html">sem_post()</a></i>,
and
<i><a href="sem_close.html">sem_close()</a></i>.
The semaphore remains usable by this process until the semaphore is closed
by a successful call to
<i><a href="sem_close.html">sem_close()</a></i>,
<i><a href="_exit.html">_exit()</a></i>,
or one of the
<i>exec</i>
functions.
<p>
The
<i>oflag</i>
argument controls whether the semaphore is created
or merely accessed by the call to
<i>sem_open()</i>.
The following flag bits may be set in
<i>oflag</i>:
<dl compact>

<dt>O_CREAT<dd>
This flag is used to create a semaphore if it does not already exist.
If O_CREAT is set and the semaphore already exists, then
O_CREAT has no effect, except as noted under O_EXCL.
Otherwise,
<i>sem_open()</i>
creates a named semaphore.
The O_CREAT flag requires a third and a fourth argument:
<i>mode</i>,
which is of type
<b>mode_t</b>,
and
<i>value</i>,
which is of type
<b>unsigned int</b>.
The semaphore is created with an initial value of
<i>value</i>.
Valid initial values for semaphores are less than or equal to
SEM_VALUE_MAX.

The user ID of the semaphore is set
to the effective user ID of the process;
the group ID of the semaphore is set
to a system default group ID or to the effective group ID of the process.
The permission bits of the semaphore are set to the value of the
<i>mode</i>
argument except those set in the file mode creation mask of the process.
When bits in
<i>mode</i>
other than the file permission bits are specified, the effect is unspecified.

After the semaphore named
<i>name</i>
has been created by
<i>sem_open()</i>
with the O_CREAT flag, other processes can connect to the semaphore by calling
<i>sem_open()</i>
with the same value of
<i>name</i>.

<dt>O_EXCL<dd>
If O_EXCL and O_CREAT are set,
<i>sem_open()</i>
fails if the semaphore
<i>name</i>
exists.
The check for the existence of the semaphore
and the creation of the semaphore if it does not exist
are atomic with respect to other processes executing
<i>sem_open()</i>
with O_EXCL and O_CREAT set.
If O_EXCL is set and O_CREAT
is not set, the effect is undefined.

If flags other than O_CREAT and O_EXCL
are specified in the
<i>oflag</i>
parameter, the effect is unspecified.

</dl>
<p>
The
<i>name</i>
argument points to a string naming a semaphore object.
It is unspecified whether the name appears in the file system
and is visible to functions that take pathnames as arguments.
The
<i>name</i>
argument conforms to the construction rules for a pathname.
If
<i>name</i>
begins with the slash character, then processes calling
<i>sem_open()</i>
with the same value of
<i>name</i>
will refer to the same semaphore object,
as long as that name has not been removed.
If
<i>name</i>
does not begin with the slash character,
the effect is implementation-dependent.
The interpretation of slash
characters other than the leading slash character in
<i>name</i>
is implementation-dependent.
<p>
If a process makes multiple successful calls to
<i>sem_open()</i>
with the same value for
<i>name</i>,
the same semaphore address is returned for each such successful call,
provided that there have been no calls to
<i><a href="sem_unlink.html">sem_unlink()</a></i>
for this semaphore.
<p>
References to copies of the semaphore
produce undefined results.
</blockquote><h4><a name = "tag_000_008_309">&nbsp;</a>RETURN VALUE</h4><blockquote>
Upon successful completion,
the function returns the address of the semaphore.
Otherwise, it will return a value of SEM_FAILED and set
<i>errno</i>
to indicate the error. The symbol SEM_FAILED is defined in the header
<i><a href="semaphore.h.html">&lt;semaphore.h&gt;</a></i>.
No successful return from
<i>sem_open()</i>
will return the value SEM_FAILED.
</blockquote><h4><a name = "tag_000_008_310">&nbsp;</a>ERRORS</h4><blockquote>
If any of the following conditions occur, the 
<i>sem_open()</i>
function will return SEM_FAILED and set
<i>errno</i>
to the corresponding value:
<dl compact>

<dt>[EACCES]<dd>
The named semaphore
exists and the permissions specified by
<i>oflag</i>
are denied, or
the named semaphore
does not exist and permission to create
the named semaphore
is denied.

<dt>[EEXIST]<dd>
O_CREAT and O_EXCL are set and the named semaphore
already exists.

<dt>[EINTR]<dd>
The
<i>sem_open()</i>
operation was interrupted by a signal.

<dt>[EINVAL]<dd>
The
<i>sem_open()</i>
operation is not supported for the given name, or
O_CREAT was specified in
<i>oflag</i>
and
<i>value</i>
was greater than SEM_VALUE_MAX.

<dt>[EMFILE]<dd>
Too many semaphore descriptors or
file descriptors are currently in use by this process.

<dt>[ENAMETOOLONG]<dd>

The length of the
<i>name</i>
string exceeds PATH_MAX,
or a pathname component is longer than
NAME_MAX while _POSIX_NO_TRUNC is in effect.

<dt>[ENFILE]<dd>
Too many semaphores are currently open in the system.

<dt>[ENOENT]<dd>
O_CREAT is not set and the named semaphore
does not exist.

<dt>[ENOSPC]<dd>
There is insufficient space for the creation of the new
named semaphore.

<dt>[ENOSYS]<dd>
The function
<i>sem_open()</i>
is not supported by this implementation.

</dl>
</blockquote><h4><a name = "tag_000_008_311">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_008_312">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_008_313">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_008_314">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="semctl.html">semctl()</a></i>,
<i><a href="semget.html">semget()</a></i>,
<i><a href="semop.html">semop()</a></i>,
<i><a href="sem_close.html">sem_close()</a></i>,
<i><a href="sem_post.html">sem_post()</a></i>,
<i><a href="sem_trywait.html">sem_trywait()</a></i>,
<i><a href="sem_unlink.html">sem_unlink()</a></i>,
<i><a href="sem_wait.html">sem_wait()</a></i>,
<i><a href="semaphore.h.html">&lt;semaphore.h&gt;</a></i>.
</blockquote><h4>DERIVATION</h4><blockquote>
Derived from the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995)
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

